Rover 25 Presentation/Rover25_Presentation_CD.bin/Tool2.cst/00005_Script_Rotation (time-based)

Text File | 2000-01-31 | 18KB | 594 lines

-- DESCRIPTION --

on getBehaviorDescription me
  return "¼
TIME-BASED ROTATION BEHAVIOR"&RETURN&RETURN&"¼
Rotates a sprite through a given angle over a given time.  ¼
Positive angles rotate sprites clockwise, negative angles rotate ¼
counterclockwise.  Angles greater than 360░ will result in ¼
more than one complete rotation."&RETURN&RETURN&"¼
PERMITTED MEMBER TYPES:"&RETURN&PermittedMemberTypes (me)&RETURN&RETURN&"¼
PARAMETERS:"&RETURN&"¼
* Initial rotation angle"&RETURN&"¼
* Angle to rotate (negative angles = anticlockwise)"&RETURN&"¼
* Duration of the rotation (1 tick to 5 days"&RETURN&"¼
* Start rotating on beginsprite (TRUE | FALSE)"&RETURN&RETURN&"¼
PUBLIC METHODS:"&RETURN&"¼
=> Modify initial angle"&RETURN&"¼
=> Modify angle to rotate"&RETURN&"¼
=> Modify duration"&RETURN&"¼
=> Stop/restart rotation"&RETURN&"¼
=> Pause/resume rotation"&RETURN&"¼
=> Reverse direction"&RETURN&"¼
=> Obtain current angle of sprite"&RETURN&"¼
=> Obtain the angle turned per tick"&RETURN&"¼
=> Obtain behavior reference"
end getBehaviorDescription


on getBehaviorTooltip me
  return "¼
Use with Bitmap, Flash, Text,"&RETURN&"¼
and Vector Shape members."&RETURN&RETURN&"¼
Turn a sprite through a given"&RETURN&"¼
angle at a steady pace."&RETURN&"¼
Use Lingo to control rotation."
end getBehaviorTooltip



-- NOTES FOR DEVELOPERS --

-- This behavior uses four angle properties:
-- * myInitialAngle: the starting angle for the rotation
-- * myTotalAngle:   how many degrees the sprite is to rotate through
-- * myAnglePerTick: the angle the sprite will turn on each tick
-- * myFinalAngle:   the angle at which the sprite will stop rotating
--
-- I calculate myFinalAngle in the StartRotation handler by adding
-- myTotalAngle to myInitialAngle.  I divide myTotalAngle by the duration
-- to obtain myAnglePerTick.
--
-- I use five properties to deal with the time:
-- * myDuration:   the total number of ticks during which the sprite will turn
-- * myTicksLeft:  the number of ticks left to turn
-- * myPauseTicks: the number of frames left to turn when the sprite is paused
-- * myStopTicks:  value that the ticks will have when the rotation ends
-- * myTimeUnit:   #ticks, #seconds, #minutes or #hours
--
-- The main handler is Turn me, activated on each prepareFrame.  I first
-- determine how many ticks are left to run (myTicksLeft), then calculate what
-- angle the sprite will turn in this time.  I obtain the current angle of the
-- sprite by subtracting this angle from myFinalAngle.
--
-- The prepareFrame handler only calls Turn if myTicksLeft is not zero.
-- I block myTicksLeft at zero when the time is up, with the command:
--
--   myTicksLeft = max (0, (myStopTicks - the ticks))
--
-- I use myTicksLeft both as a boolean (TRUE|FALSE) value and as an integer.
-- Setting myTicksLeft to zero effectively stops the rotation.  If I first save
-- the value of myTicksLeft in myPauseTicks, then I can restore this value
-- later to make  the sprite resume its rotation from the point at which it was
-- paused.
--
-- To reverse the direction of the sprite, I invert two values - myTotalAngle
-- and myAnglePerTick - and I set myTicksLeft so that it will reach zero when
-- the sprite returns to its initial angle.
--
-- The TimedRotation_SetDuration call lets you change the value of
-- myDuration even while the sprite is rotating.  To ensure that the sprite
-- turns the correct total angle, I adjust myAnglePerTick  and set myTicksLeft
-- in proportion to the angle the sprite has still to turn.

-- PUBLIC METHODS
-- This behavior supports the following external calls.  See the handlers
-- themselves for details and copy-and-paste examples.
--
-- * TimedRotation_SetInitialAngle me, theAngle
-- * TimedRotation_SetTotalAngle me, theAngle
-- * TimedRotation_SetDuration me, duration, timeUnit
-- * TimedRotation_ToggleActive me, trueOrFalse
-- * TimedRotation_TogglePause me, trueOrFalse
-- * TimedRotation_ToggleDirection me, newDirection
-- * TimedRotation_GetAngle me
-- * TimedRotation_GetIncrement me
-- * TimedRotation_GetReference



-- HISTORY --

-- 28 September 1998: written for the D7 Behaviors Palette by James Newton
-- 23 November  1998: Public Methods descriptions added.  ErrorAlert modified.



-- PROPERTIES --

property mySprite
-- error checking
property getPDLError
-- author-defined parameters
property myInitialAngle
property myTotalAngle
property myDuration
property myTimeUnit
property myTicksLeft
-- internal properties
property myFinalAngle
property myAnglePerTick
property myStopTicks
property myPauseTicks



-- EVENT HANDLERS --

on beginSprite me
  Initialize me

end beginSprite


on prepareFrame me
  --  if myTicksLeft then Turn me
  Turn me
end prepareFrame



-- CUSTOM HANDLERS --

on Initialize me -- sent by beginSprite
  mySprite = sprite(me.spriteNum)

  -- Error checking
  theMember  = mySprite.member
  memberType = theMember.type
  if PermittedMemberTypes(me).getPos(memberType) then
    if memberType = #text then
      if theMember.boxType = #scroll then
        ErrorAlert (me, #scrollingText, theMember)
        theMember.boxType = #fixed
      end if
    end if
  else
    ErrorAlert (me, #invalidMemberType, memberType)
  end if
  -- End of error checking

  myDuration = ConvertToTicks (me, myDuration, myTimeUnit)

  if myTicksLeft then
    SetAnglePerTick me
    StartRotation me
  end if
end Initialize


on ConvertToTicks me, duration, timeUnit
  -- sent by Initialize, _SetDuration
  -- Converts the chosen duration to a platform-dependent number of ticks
  case timeUnit of
    void, #ticks: -- nothing
    #seconds: duration = duration * 60
    #minutes: duration = duration * 60 * 60
    #hours:   duration = duration * 60 * 60 * 60
    otherwise
      return #invalidSymbolError
  end case
  return integer (duration)
end ConvertToTicks


on SetAnglePerTick me
  -- sent by Initialize, _SetFrameCount, _ToggleActive
  myAnglePerTick = myTotalAngle / myDuration
end SetAnglePerTick


on StartRotation me -- sent by Initialize, _ToggleActive
  mySprite.rotation = myInitialAngle
  myFinalAngle      = myInitialAngle + myTotalAngle
  myTicksLeft       = myDuration
  myStopTicks       = the ticks + myDuration
end StartRotation


on Turn me -- sent by prepareFrame
  ticksLeft         = myStopTicks - the ticks
  if myTicksLeft    = ticksLeft then exit

  myTicksLeft       = max (0, ticksLeft)
  remainingAngle    = myAnglePerTick * myTicksLeft
  newAngle          = myFinalAngle - remainingAngle
  mySprite.rotation = newAngle
end Turn



-- PUBLIC METHODS (responses to #sendSprite, #sendAllSprites, #call) --

on TimedRotation_SetInitialAngle me, theAngle
  -- Sets initial angle (takes effect from next _ToggleActive call)
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_SetInitialAngle, 180.0)
  --
  --  sendAllSprites (#TimedRotation_SetInitialAngle, 90.0)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_SetInitialAngle, rotationRef, 45.0)

  -- Error check
  case ilk (theAngle) of
    #float, #integer: -- nothing
    otherwise
      return #invalidTypeError
  end case
  -- End of error check

  myInitialAngle = theAngle
end TimedRotation_SetInitialAngle


on TimedRotation_SetTotalAngle me, theAngle
  -- Sets angle to rotate (takes effect from next _ToggleActive call)
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_SetTotalAngle, 180.0)
  --
  --  sendAllSprites (#TimedRotation_SetTotalAngle, 720.0)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_SetTotalAngle, rotationRef, 45.0)

  case ilk (theAngle) of
    #float:   myTotalAngle = theAngle
    #integer: myTotalAngle = float (theAngle)
    otherwise
      -- Error check
      return #invalidTypeError
  end case
end TimedRotation_SetTotalAngle


on TimedRotation_SetDuration me, duration, timeUnit
  -- Modifies the time that rotation is to last.
  -- duration can be any positive number (integer|float)
  -- timeUnit can be void|#ticks|#seconds|#minutes|#hours (void acts as #ticks)
  -- Changes remaining time proportionately if sprite is currently rotating
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_SetDuration, 18, #seconds)
  --
  --  sendAllSprites (#TimedRotation_SetDuration, 1.7, #minutes)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_SetDuration, rotationRef, 45, #ticks)

  -- Error check
  case ilk (duration) of
    #integer, #float:
      if duration < 1 then
        return #outOfRangeError
      end if
    otherwise
      return #invalidTypeError
  end case
  duration = ConvertToTicks (me, duration, timeUnit)
  if ilk (duration) <> #integer then
    return duration
  end if
  -- End of error check

  if myTicksLeft then
    myTicksLeft = (myTicksLeft * duration) / myDuration
    myStopTicks = the ticks + myTicksLeft
  else if myPauseTicks then
    myPauseTicks = (myPauseTicks * duration) / myDuration
  end if
  myDuration = duration
  SetAnglePerTick me
end TimedRotation_SetDuration


on TimedRotation_ToggleActive me, trueOrFalse
  -- Stops rotation or restarts it from myInitialAngle.
  -- trueOrFalse is an optional parameter
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_ToggleActive)
  --
  --  sendAllSprites (#TimedRotation_ToggleActive, TRUE)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_ToggleActive, rotationRef, 0)

  if voidP (trueOrFalse) then
    myTicksLeft = not myTicksLeft
  else if ilk (trueOrFalse) <> #integer then
    -- Error check
    return #invalidTypeError
  else
    myTicksLeft = trueOrFalse <> 0
  end if

  if myTicksLeft then
    SetAnglePerTick me
    StartRotation me
  end if
end TimedRotation_ToggleActive


on TimedRotation_TogglePause me, trueOrFalse
  -- Pauses or continues rotation from where it was paused
  -- trueOrFalse is an optional parameter
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_TogglePause)
  --
  --  sendAllSprites (#TimedRotation_TogglePause, TRUE)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_TogglePause, rotationRef, 0)

  pauseTicks = myTicksLeft
  if voidP (trueOrFalse) then
    myTicksLeft = not myTicksLeft
  else if ilk (trueOrFalse) <> #integer then
    -- Error check
    return #invalidTypeError
  else
    if (not myTicksLeft = not trueOrFalse) then
      -- Don't change pause state
      exit
    end if

    myTicksLeft = trueOrFalse
  end if

  if myTicksLeft then
    myTicksLeft  = myPauseTicks
    myStopticks  = the ticks + myTicksLeft
    myPauseTicks = 0
  else
    myPauseTicks = pauseTicks
  end if
end TimedRotation_TogglePause


on TimedRotation_ToggleDirection me, newDirection
  -- Reverse/sets the direction of rotation.  The sprite will stop rotating
  -- when it reaches myInitialAngle.  (If you use this command an even number
  -- of times, the sprite will stop once it has turned through myTotalAngle).
  -- newDirection is an optional parameter.  It can take the values
  -- void|#clockwise|TRUE|#antiClockwise|#counterClockwise|FALSE
  -- A void value for newDirection will reverse the direction of rotation
  -- Examples:
  --
  --  sendSprite (1, #TimedRotation_ToggleDirection)
  --
  --  sendAllSprites (#TimedRotation_ToggleDirection, #clockwise)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  call (#TimedRotation_ToggleDirection, rotationRef, 0)

  if voidP (newDirection) then
    anglePerTick = -myAnglePerTick
  else
    case newDirection of
      #clockwise, TRUE:
        anglePerTick = abs (myAnglePerTick)
      #antiClockwise, #counterClockwise, FALSE:
        anglePerTick = -abs (myAnglePerTick)
      otherwise
        -- Error check
        return #invalidTypeError
    end case
    if myAnglePerTick = anglePerTick then exit
  end if

  -- Return to initial angle
  myAnglePerTick = anglePerTick
  if myPauseTicks then
    myPauseTicks = myDuration - myPauseTicks
    myFinalAngle = mySprite.rotation + (myAnglePerTick * myPauseTicks)
  else -- if myTicksLeft then
    myTicksLeft  = myDuration - myTicksLeft
    myStopTicks  = the ticks + myTicksLeft
    myFinalAngle = mySprite.rotation + (myAnglePerTick * myTicksLeft)
  end if
  myTotalAngle = -myTotalAngle
end TimedRotation_ToggleDirection


on TimedRotation_GetAngle me
  -- Returns the current angle of the sprite
  -- Examples:
  --
  --  put sendSprite (1, #TimedRotation_GetAngle)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  put call (#TimedRotation_GetAngle, rotationRef)

  return mySprite.rotation
end TimedRotation_GetAngle


on TimedRotation_GetIncrement me
  -- Returns the angle the sprite turns on each frame
  -- Examples:
  --
  --  put sendSprite (1, #TimedRotation_GetIncrement)
  --
  --  rotationRef = sendSprite (1, #TimedRotation_GetReference)
  --  put call (#TimedRotation_GetIncrement, rotationRef)

  return myAnglePerTick
end TimedRotation_GetIncrement


on TimedRotation_GetReference me, theList
  -- Returns a reference to the current behavior.  theList is an optional
  -- parameter.  Use an empty list in a sendAllSprites call to return a
  -- list of all "Rotation (time-based)" behaviors in the current frame.  Use
  -- an empty linear list to obtain a list of behaviors, or an empty
  -- property list to return a list with sprite numbers as the
  -- properties and behavior references as the values.  Examples :
  --
  --   put sendAllSprites (#TimedRotation_GetReference, [])
  --   -- [<offspring "Rotation (time-based)" 2 2f1b594>]
  --
  --   put sendAllSprites (#TimedRotation_GetReference, [:])
  --   -- [1: <offspring "Rotation (time-based)" 2 2f1b594>]
  --
  -- If you leave "theList" void then the handler will return a reference to
  -- the behavior on the given sprite (using sendSprite) or the highest sprite
  -- with the behavior (using sendAllSprites).  Examples:
  --
  --   put sendSprite (1, #TimedRotation_GetReference)
  --   -- <offspring "Rotation (time-based)" 2 2f1b594>
  --
  --   put sendAllSprites (#TimedRotation_GetReference)
  --   -- <offspring "Rotation (time-based)" 2 2f0dac0>

  case ilk (theList) of
    #list: theList.append(me)
    #propList: theList.addProp(me.spriteNum, me)
    otherwise
      return me
  end case
  return theList
end TimedRotation_GetReference



-- ERROR CHECKING --

on ErrorAlert me, theError, data
  -- sent by getPropertyDescriptionList, Initialize

  case theError of
    #getPDLError:
      alert "¼
Error: This behavior works only with the following members types:   "&¼
permittedMemberTypes(me)&RETURN&RETURN&"¼
Hit OK and then delete this behavior from the sprite."&RETURN&"¼
For more information on deleting Behaviors, see the Help system."
      if the optionDown then
        return ¼
 [ ¼
 #getPDLError: ¼
 [ ¼
  #comment: "ERROR:  Wrong member type.  Click 'Cancel'.", ¼
  #format:  #string, ¼
  #range:   [""], ¼
  #default:  "" ¼
 ] ¼
]
      end if

    otherwise
      -- Determine the behavior's name
      behaviorName = string (me)
      delete word 1 of behaviorName
      delete the last word of behaviorName
      delete the last word of behaviorName
      -- Convert #data to useful value
      case data.ilk of
        #void: data = "<void>"
        #symbol: data = "#"&data
      end case

      case theError of
        #invalidMemberType:
          alert "¼
BEHAVIOR ERROR: Frame "&the frame&", Sprite "&me.spriteNum&RETURN&RETURN&"¼
Behavior "&behaviorName&" only functions with the following member types:"&¼
RETURN&permittedMemberTypes()&RETURN&RETURN&"¼
Current type = "&data
          halt

        #scrollingText:
          if the runMode = "Author" then
            memberName = data.name
            if memberName = "" then
              memberName = string (data)
              delete memberName.word [1]
              delete the last char of memberName
            else
              memberName = QUOTE&memberName"E
            end if
            alert "¼
BEHAVIOR ERROR: Frame "&the frame&", Sprite "&me.spriteNum&RETURN&"¼
Behavior "&behaviorName&RETURN&RETURN&"¼
Scroll bars of Text members cannot be rotated.  The boxType of the member "&¼
memberName&" has been set to #fixed."
          end if

      end case
  end case
end ErrorAlert



-- AUTHOR-DEFINED PARAMETERS --

on getPropertyDescriptionList me

  if not the currentSpriteNum then exit

  -- Error check
  theMember = sprite(the currentSpriteNum).member
  memberType = theMember.type
  permittedTypes = PermittedMemberTypes(me)
  if not permittedTypes.getPos(memberType) then
    return errorAlert (me, #getPDLError, permittedTypes)
  end if
  -- End of error check

  return ¼
[ ¼
 #myInitialAngle: ¼
 [ ¼
  #comment: "Initial angle:", ¼
  #format:  #float, ¼
  #default:  sprite(the currentSpriteNum).rotation ¼
 ], ¼
 #myTotalAngle: ¼
 [ ¼
  #comment: "Turn clockwise through how many degrees?", ¼
  #format:  #float, ¼
  #default:  360 ¼
 ], ¼
 #myDuration: ¼
 [ ¼
  #comment: "Time taken to turn:", ¼
  #format:  #integer, ¼
  #range:  [#min: 1, #max: 120], ¼
  #default:  60¼
 ], ¼
 #myTimeUnit: ¼
 [ ¼
  #comment: "", ¼
  #format:  #symbol, ¼
  #range:  [#ticks, #seconds, #minutes, #hours], ¼
  #default: #seconds ¼
 ], ¼
 #myTicksLeft: ¼
 [ ¼
  #comment: "Start rotating on beginSprite?", ¼
  #format:  #boolean, ¼
  #default:  TRUE¼
 ] ¼
]
end getPropertyDescriptionList


on PermittedMemberTypes me
  -- sent by: getBehaviorDescription, getPropertyDescriptionList
  -- ErrorAlert
  return [#bitmap, #flash, #text, #vectorShape]
end PermittedMemberTypes